<html>
<head>
<title>RAM</title>
<link rel="stylesheet" type="text/css" href="../../help.css">
</head>

<body bgcolor="FFFFFF">

<h1><img  align="center" src="../../../icons/ram.gif" width="32" height="32">
<em>RAM</em></h1>

<p><table>
<tr><td><strong>Library:</strong></td>
	<td><a href="index.html">Memory</a></td></tr>
<tr><td><strong>Introduced:</strong></td>
	<td>2.0 Beta 1</td></tr>
<tr><td valign="top"><strong>Appearance:</strong></td>
    <td><table>
            <tr><th></th><th width="240">Separate Data Buses</th><th>Bidirectional Data bus</th></tr>
            <tr><th height="140" align="right">Classic Logisim:</th><td rowspan="2"
                    colspan="2" valign="top">
                    <img src="../../../img-libs/ram.png"></td></tr>
            <tr><th align="right">ANSI:</th></tr></table></td></tr>
</table></p>

<h2>Behavior</h2>

<p>The RAM component, easily the most complex component in Logisim's
built-in libraries, stores up to 16,777,216 values (specified in the Address
Bit Width attribute), each of which can include up to to 32 bits
(specified in the Data Bit Width attribute). The circuit can load and
store values in RAM, either one at a time, in pairs, or four at a time. Also, the user can modify individual values
interactively via the Poke Tool, or the user can edit, export, or import the
contents via the Menu Tool.</p>

<p>Current values are displayed in the component. Addresses are shown in hex to
the left of the display area, and memory contents are shown in hex inside the
display area. The value at the currently selected address is displayed with a
dark highlight and white text.</p>


<p>The RAM component supports two different interfaces, depending on the
Databus implementation attribute.</p>

<dl>

<dt>One bidirectional data bus</dt>
<dd><p>The component includes a single port on its east side that serves for both
loading and storing data. Which operation is performed&mdash;loading or
storing&mdash;depends on the inputs labeled
<var>L</var> and <var>S</var>: <var>L=1</var> (or floating) indicates to load (from RAM to the data bus) the data at the address
designated on the component's west side, and <var>S=1</var> indicates to store (from the data
bus to RAM) the data given on the port into the given address. To transmit data into and out of the component in both
directions on a single bus wire, you will need to use a <a
    href="../basic/controlled.html"><img class="icon"
src="../../../icons/controlledBuffer.gif"> Tri-State Buffer</a>, as illustrated in the
example below, or other components that support floating outputs (e.g.
components that have an 'Output Value' attribute with support for floating
outputs).
</p>

<center><img src="../../../img-libs/ramdemo.png"></center></dd>

<dt>Separate data bus for read and write</dt>
<dd><p>Two data ports are provided&mdash;one input data port on the west side
for storing data into RAM, and a separate output port on the east side for
loading data from RAM. This style of data interface removes the necessity of
dealing with the Tri-State Buffers and so it generally easier to use. With this
interface, the output port will always be enabled, and there is no <var>L</var>
control port: effectively, the RAM will load values to the output databus on
every cycle. The <var>S</var> control port controls whether data is stored.
</p></dd>

</dl>

<h2>Single, Dual, and Quad Lines Modes</h2>

<p>Logisim RAM has a 'Line Size' attribute that controls how many locations
("lines") of memory are accessed at a time. Setting 'Line Size' to 'Single' is
the simplest case: at most one location is accessed during each clock cycle, and
there is one databus labeled <var>D</var> (either a single bidirectional port,
or a pair of one input and one output port both labeled <var>D</var>). When
'Line Size' is set to 'Dual', however, the RAM component can read or write up to
two locations simultaneously, and there are two databuses (either two
bidirectional ports, or two pairs of unidirectional ports), labeled <var>D</var>
and <var>1</var>. In 'Quad' mode, RAM will read or write up to four locations,
with four databuses labeled <var>D</var>, <var>1</var>, <var>2</var>, and
<var>3</var>. The addresses accessed are all consective: for 'Dual' line mode,
RAM will access addresses <var>A</var> and <var>A+1</var>; for 'Quad' line mode,
RAM will access addresses <var>A</var>, <var>A+1</var>,  <var>A+2</var>, and
<var>A+3</var>.</p> 

<p>In 'Single' line mode, the single input <var>S</var> controls
whether a store operation is performed for the given address.
In 'Dual' and 'Quad' line modes, there are additional inputs to control which
bytes (if any) are stored during a store operation. For example, in 'Quad' mode,
there are control signals labeled <var>S0</var>, <var>S1</var>, <var>S2</var>,
and <var>S3</var>, which control whether a store is performed for addresses
addresses <var>A</var>, <var>A+1</var>,  <var>A+2</var>, and <var>A+3</var>,
respectively.</p> 

<h2>Address Alignment</h2>

<p>In 'Dual' and 'Quad' line modes, the selected address must be aligned to a
multiple of 2 or 4, respectively. There is no support for mis-aligned accesses.
This means the lowest bit or lowest two bits of the address must always be zero
in those modes. If the address is mis-aligned, RAM will not store data, and it
will output all error (E) values instead of loading data from the RAM contents.

<p>The decision to omit support in Logisim for mis-aligned addresses is
deliberate. Support for mis-aligned addresses is not trivial in many actual
scenarios: a memory chip may require multiple row accesses, for example, in
order to perform a mis-aligned read. In addition, FPGA synthesis is
substantially simpler when mis-aligned addresses are not permitted.</p>

<h2>Importing and Exporting Memory Contents</h2>

The contents of memory can be imported from an external data file, or exported
to an external file. A variety of file formats are supported: see <a
href="../../guide/mem/importexport.html">Memory Import/Export Format</a> in the
<em>User's Guide</em> for details.</p>

<h2>Pins (assuming "Classic Logisim" appearance)</h2>

<dl>

<dt><var>A</var> on west edge (input, bit width matches Address Bit Width attribute)</dt>
<dd>Selects which of the values in memory is currently being accessed by the
circuit. In 'Dual' and 'Quad' line mode, the address <var>A</var> must be a
multiple of 2 or 4, respectively, and two or four consecutive addresses are
accessed starting at address <var>A</var>.</dd>

<dt><var>D</var> on west edge (input, bit width matches Data Bit Width attribute)</dt>
<dd>This input is present only if "separate data buses" is selected
for the Databus implementation attribute. When a store is requested (via the clock changing
from 0 to 1 while <em>S</em> is 1 and <em>S0</em> if present is also 1), the
value found at this port is stored into memory at the currently selected address.</dd>

<dt><var>1</var> on west edge (input, bit width matches Data Bit Width attribute)</dt>
<dd>This input is present only if "Dual" or "Quad" line mode is selected and
"separate data buses" is selected for the Databus implementation attribute. When a store
is requested (via the clock changing from 0 to 1 while <em>S1</em> is 1), the
value found at port <em>1</em>is stored into memory at <var>A+1</var>, i.e. 1
location beyond the currently selected address.</dd>

<dt><var>2</var> and <var>3</var> on west edge (inputs, bit width matches Data Bit Width attribute)</dt>
<dd>These inputs are present only if "Quad" line mode is selected and
"separate data buses" is selected for the Databus implementation attribute. They behave
similarly to the <var>1</var> input, but using control signals <em>S2</em> and
<em>S3</em>, respectively, and addresses <var>A+2</var> and <var>A+3</var>,
respectively.</dd>

<dt><var>D</var> on east edge (input/output or output, bit width matches Data Bit Width attribute)</dt>
<dd>If <var>L</var> is 1 or floating (or if the <var>L</var> input is not
present), then the RAM component emits the value found at the currently selected
address on this port, unless the address is mis-aligned in which case an error
(E) value is emitted instead. If there is a single bidirectional load/store
port, the value read from this port is stored whenever a store is
requested.</dd>

<dt><var>1</var>, <var>2</var>, <var>3</var> on east edge (inputs/outputs or
outputs, bit width matches Data Bit Width attribute)</dt> <dd>These ports are
present only if "Dual" or "Quad" line mode is selected. They each behave
similarl to the <var>D</var> input/output or output port, but using addresses
<var>A+1</var>,  <var>A+2</var>, and <var>A+3</var>, respectively.</dt>

<dt><var>S</var> on west edge (input, bit width 1)</dt>
<dd>Store: When it is 1, a clock pulse will result
in storing data into memory at the current selected address(es).</dd>

<dt><var>S0</var>, <var>S1</var>, <var>S2</var>, and <var>S3</var> on west edge
(inputs, bit width 1)</dt> <dd>Store i: Only present in "Dual" or "Quad" line
modes, these individually control the store behavior for each of the selected
lines. Address <var>A+i</var> is only written when both <var>S</var> and
<var>Si</var> are 1.</dd>

<dt>triangle on west edge (input, bit width 1)</dt>
<dd>Clock input: Controls the timing of store requests.
When <var>S</var> is 1, and the clock input rises from 0 to 1 (or is triggered
according to the 'Trigger' attribute) while <var>S</var> is 1 (and some of the
<var>Si</var> inputs, if present, are also 1), then the value at the data input
bus(es) is immediately written into the currently selected address. Note that
the clock has no effect on load actions: loads happen asynchronously and
continously, regardless of the clock triggers.</dd>

<dt><var>L</var> on west edge (input, bit width 1)
<dd>Load: This port is only present if there bidirectional load/store ports are
used. When <var>L=1</var>, the bidirectional data port or ports are set to
output mode, and the value at the current selected address(es) are output to
those data ports.

</dl>

<h2>Attributes</h2>

<p>When the component is selected or being added,
the digits '0' through '9' alter its <q>Address Bit Width</q> attribute
and Alt-0 through Alt-9 alter its <q>Data Bit Width</q> attribute.</p>

<dl>

<dt>Address Bit Width</dt>
<dd>The bit width of the address bits. The number of values stored in
RAM is 2<sup><var>addrBitWidth</var></sup>.</dd>

<dt>Data Bit Width</dt>
<dd>The bit width of each individual value in memory.</dd>

<dt>Line Size</dt>
<dd>Allows for Single, Dual, or Quad line mode.</dd>

<dt>Trigger</dt>
<dd>Configures how the clock input is interpreted. This only affects store
operations. When a store operation is selected via the <var>S</var> and
<var>Si</var> inputs, the value <q>rising edge</q> indicates that the memory
should store values at the instant when the clock rises from 0 to 1. The
<q>falling edge</q> value indicates that it should update at the instant the
clock falls from 1 to 0. The <q>high level</q> value indicates that the memory
should update continuously whenever the clock input is 1. And the <q>low
level</q> value indicates that it should update continuously when the clock
input is 0.</dd>

<dt>Memory Type</dt>
<dd>If set to 'Volatile' the memory contents will be lost when the simulation is
reset or when Logisim exits. In addition, FPGA synthesis will initialize
volatile memory to all zeros. If set to 'Non-Volatile', the memory contents will
be retained even when the simulation is reset or when Logisim exits, and FPGA
synthesis will use the current contents of the memory at the time sythesis
occurs to initialize the FPGA memory.</dd>

<dt>Databus implementation</dt>
<dd>Configures which of the two styles of data interface is used for communicating data
into and out of the RAM.</dd>

<dt>Label</dt>
<dd>The text within the label associated with the register.</dd>

<dt>Label Font</dt>
<dd>The font with which to render the label.</dd>

<dt>Appearance</dt>
<dd>Selects between the "Classic Logisim" appearance style, which is somewhat
more compact, or "ANSI" style, which is more conventional but larger.</dd>

</dl>

<h2>Poke Tool Behavior</h2>

<p>Clicking the RAM component brings keyboard and mouse focus to the RAM
(indicated by a red rectangle), allowing for the contents to be viewed or
edited. Because Poke Tool editing all takes place within a very small space, the
interface for this is severely but necessarily constrained. <!-- (see <a
href="../../guide/mem/poke.html">poking memory</a> in the <em>User's Guide</em>
for additional details about using the Poke Tool with memory).--> For all but the
simplest editing, it is more convenient to right-click the RAM and select "Edit
Contents..." to bring up the <a href="../../guide/mem/hex.html">integrated hex
editor</a>.</p>

<p>The Poke Tool has two modes of operation: You can edit the address displayed,
and you can edit an individual value at some memory location.</p>

<p><b>Editing Addresses:</b> Use the Poke Tool and click anywhere within the
memory component but <em>outside</em> the gray box holding the memory contents.
Logisim will draw a red rectangle around the address at the upper left corner.
From here:
<ul>
    <li><p>Typing <span class="key">R</span> or <span class="key">r</span> will
    clear the contents of memory.</li>
    <li><p>Typing hex digits will change the address (assuming the new address
    isn't too large) and scroll the memory contents to show that address.</li>
    <li><p>Scrolling with the mouse wheel increments or decrements the address
    and scrolls the memory forward or backward.
    <li><p>The <span class="key">Down</span> (or <span class="key">Enter</span>)
    key will increment the address and scroll the memory contents forward by one
    row.</li>
    <li><p>The <span class="key">Up</span> (or <span class="key">Backspace</span>
    or <span class="key">Delete</span>) keys will also increment or decrement
    the address to key will decrement the address and scroll the memory contents
    backwards by one row.</li>
    <li><p>The <span class="key">Page Down</span> (or <span
        class="key">Space</span>) and <span class="key">Page Up</span> keys will
    increment or decrement the address to scroll the memory contents forward or
    backward by one full page.</li>
</ul>

<p><b>Editing Contents:</b> Use the Poke Tool and click anywhere within the
memory component <em>within</em> the gray box holding the memory contents.
Logisim will draw a red rectangle around the memory cell currently being
edited. From here:
<ul>
    <li><p>Typing <span class="key">R</span> or <span class="key">r</span> will
    clear the contents of memory.</li>
    <li><p>Typing hex digits will change the contents of that cell.</li>
    <li><p>Scrolling with the mouse wheel moves up or down to an adjacent memory
    cell.</li>
    <li><p>The <span class="key">Up</span>, <span class="key">Down</span>, <span
        class="key">Left</span>, and <span class="key">Right</span> arrow keys
    move to an adjacent memory cell.
    <li><p>The <span class="key">Page Up</span> and <span class="key">Page
        Down</span> keys move up or down by a full page.
    <li><p>The <span class="key">Backspace</span> (or <span
        class="key">Delete</span>) and <span class="key">Tab</span> (or <span
        class="key">Space</span>) keys similarly move to the previous or next
    memory cell.</li>
</ul>

<h2>Menu Tool Behavior</h2>

<p>Right-clicking the RAM component brings up several actions in a context menu:
<ul>
    <li><p><em><b>Edit Contents...:</b></em> Brings up the <a
        href="../../guide/mem/hex.html">integrated hex editor</a> to view and
    edit the entire memory contents in a separate window</p></li>

    <li><p><em><b>Clear Contents:</b></em> Resets all values in memory to all
    zeros.</li>

    <li><p><em><b>Load Memory Image...:</b></em> Loads entirely new memory
    contents by importing from a file. A variety of file formats are supported:
    see <a href="../../guide/mem/importexport.html">Memory Import/Export
    Format</a> in the <em>User's Guide</em> for details.</p>
    </li>

    <li><p><em><b>Save Memory Image...:</b></em> Saves the entire contents of
    memory to an external file. A variety of file formats are supported:
    see <a href="../../guide/mem/importexport.html">Memory Import/Export
    Format</a> in the <em>User's Guide</em> for details.</p>
    </li>
</ul>

<h2>FPGA Synthesis</h2><p>Supports VHDL synthesis. Only rising and falling edge
triggers are supported. Non-Volatile memory is only supported on Altera devices.
Only the "separate data bus" interface option is supported for synthesis.</p>

<p><a href="../index.html">Up to <em>Library Reference</em></a></p>

</body>
</html>
